<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.5.2" />
<title></title>
<style type="text/css">
/* Debug borders */
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
/*
  border: 1px solid red;
*/
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

tt {
  color: navy;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  font-family: sans-serif;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}

div.sectionbody {
  font-family: serif;
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}

pre {
  padding: 0;
  margin: 0;
}

span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.1em;
}
span#email {
}
span#revnumber, span#revdate, span#revremark {
  font-family: sans-serif;
}

div#footer {
  font-family: sans-serif;
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
div#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

div#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #dddddd;
  color: #777777;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > div.content {
  white-space: pre;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-family: sans-serif;
  font-weight: bold;
}
tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}


@media print {
  div#footer-badges { display: none; }
}

div#toc {
  margin-bottom: 2.5em;
}

div#toctitle {
  color: #527bbd;
  font-family: sans-serif;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}
/* Workarounds for IE6's broken and incomplete CSS2. */

div.sidebar-content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}
div.sidebar-title, div.image-title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  margin-top: 0.0em;
  margin-bottom: 0.5em;
}

div.listingblock div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock-attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock-content {
  white-space: pre;
}
div.verseblock-attribution {
  padding-top: 0.75em;
  text-align: left;
}

div.exampleblock-content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

/* IE6 sets dynamically generated links as visited. */
div#toc a:visited { color: blue; }
</style>
<script type="text/javascript">
/*<![CDATA[*/
window.onload = function(){asciidoc.footnotes();}
var asciidoc = {  // Namespace.

/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////

/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, 2006, 2009. License: GPL */

// toclevels = 1..4.
toc: function (toclevels) {

  function getText(el) {
    var text = "";
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
        text += i.data;
      else if (i.firstChild != null)
        text += getText(i);
    }
    return text;
  }

  function TocEntry(el, text, toclevel) {
    this.element = el;
    this.text = text;
    this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
    var result = new Array;
    var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
    // Function that scans the DOM tree for header elements (the DOM2
    // nodeIterator API would be a better technique but not supported by all
    // browsers).
    var iterate = function (el) {
      for (var i = el.firstChild; i != null; i = i.nextSibling) {
        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
          var mo = re.exec(i.tagName);
          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
          }
          iterate(i);
        }
      }
    }
    iterate(el);
    return result;
  }

  var toc = document.getElementById("toc");
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "_toc_" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    toc.parentNode.removeChild(toc);
},


/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////

/* Based on footnote generation code from:
 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 */

footnotes: function () {
  var cont = document.getElementById("content");
  var noteholder = document.getElementById("footnotes");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
    if (spans[i].className == "footnote") {
      n++;
      // Use [\s\S] in place of . so multi-line matches work.
      // Because JavaScript has no s (dotall) regex flag.
      note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
      noteholder.innerHTML +=
        "<div class='footnote' id='_footnote_" + n + "'>" +
        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
        n + "</a>. " + note + "</div>";
      spans[i].innerHTML =
        "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
        "' title='View footnote' class='footnote'>" + n + "</a>]";
      var id =spans[i].getAttribute("id");
      if (id != null) refs["#"+id] = n;
    }
  }
  if (n == 0)
    noteholder.parentNode.removeChild(noteholder);
  else {
    // Process footnoterefs.
    for (i=0; i<spans.length; i++) {
      if (spans[i].className == "footnoteref") {
        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
        href = href.match(/#.*/)[0];  // Because IE return full URL.
        n = refs[href];
        spans[i].innerHTML =
          "[<a href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
      }
    }
  }
}

}
/*]]>*/
</script>
</head>
<body>
<div id="header">
</div>
<div id="content">

<h2 id="_the_libevent_reference_manual_preliminaries">The Libevent Reference Manual: Preliminaries</h2>
<div class="sectionbody">
<h3 id="_libevent_from_10_000_feet">Libevent from 10,000 feet</h3><div style="clear:left"></div>
<div class="paragraph"><p>Libevent is a library for writing fast portable nonblocking IO.  Its
design goals are:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
Portability
</dt>
<dd>
<p>
    A program written using Libevent should work across all the
    platforms Libevent supports.  Even when there is no really <em>good</em>
    way to do nonblocking IO, Libevent should support the so-so
    ways, so that your program can run in restricted environments.
</p>
</dd>
<dt class="hdlist1">
Speed
</dt>
<dd>
<p>
    Libevent tries to use the fastest available nonblocking IO
    implementations on each platform, and not to introduce much
    overhead as it does so.
</p>
</dd>
<dt class="hdlist1">
Scalability
</dt>
<dd>
<p>
    Libevent is designed to work well even with programs that need to
    have tens of thousands of active sockets.
</p>
</dd>
<dt class="hdlist1">
Convenience
</dt>
<dd>
<p>
    Whenever possible, the most natural way to write a program with
    Libevent should be the stable, portable way.
</p>
</dd>
</dl></div>
<div class="paragraph"><p>Libevent is divided into the following components:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
evutil
</dt>
<dd>
<p>
    Generic functionality to abstract out the differences between
    different platforms' networking implementations.
</p>
</dd>
<dt class="hdlist1">
event and event_base
</dt>
<dd>
<p>
    This is the heart of Libevent.  It provides an abstract API to
    the various platform-specific, event-based nonblocking IO backends.
    It can let you know when sockets are ready to read or write, do
    basic timeout functionality, and detect OS signals.
</p>
</dd>
<dt class="hdlist1">
bufferevent
</dt>
<dd>
<p>
    These functions provide a more convenient wrapper around
    Libevent&#8217;s event-based core.  They let your application request
    buffered reads and writes, and rather than informing you when
    sockets are ready to do, they let you know when IO has actually
    occurred.
</p>
<div class="literalblock">
<div class="content">
<pre><tt>The bufferevent interface also has multiple backends, so that
it can take advantage of systems that provide faster ways to do
nonblocking IO, such as the Windows IOCP API.</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
evbuffer
</dt>
<dd>
<p>
    This module implements the buffers underlying bufferevents,
    and provides functions for efficient and/or convenient access.
</p>
</dd>
<dt class="hdlist1">
evhttp
</dt>
<dd>
<p>
    A simple HTTP client/server implementation.
</p>
</dd>
<dt class="hdlist1">
evdns
</dt>
<dd>
<p>
    A simple DNS client/server implementation.
</p>
</dd>
<dt class="hdlist1">
evrpc
</dt>
<dd>
<p>
    A simple RPC implementation.
</p>
</dd>
</dl></div>
<h3 id="_the_libraries">The Libraries</h3><div style="clear:left"></div>
<div class="paragraph"><p>When Libevent is built, by default it installs the following
libraries:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
libevent_core
</dt>
<dd>
<p>
    All core event and buffer functionality.  This
    library contains all the event_base, evbuffer, bufferevent,
    and utility functions.
</p>
</dd>
<dt class="hdlist1">
libevent_extra
</dt>
<dd>
<p>
    This library defines protocol-specific functionality that
    you may or may not want for your application, including HTTP, DNS,
    and RPC.
</p>
</dd>
<dt class="hdlist1">
libevent
</dt>
<dd>
<p>
    This library exists for historical reasons; it contains the
    contents of both libevent_core and libevent_extra.  You shouldn&#8217;t
    use it; it may go away in a future version of Libevent.
</p>
</dd>
</dl></div>
<div class="paragraph"><p>The following libraries are installed only on some platforms:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
libevent_pthreads
</dt>
<dd>
<p>
    This library adds threading and locking implementations based on
    the pthreads portable threading library.  It is separated from
    libevent_core so that you don&#8217;t need to link against pthreads
    to use Libevent unless you are <em>actually</em> using Libevent in a
    multithreaded way.
</p>
</dd>
<dt class="hdlist1">
libevent_openssl
</dt>
<dd>
<p>
    This library provides support for encrypted communications using
    bufferevents and the OpenSSL library.  It is separated from
    libevent_core so that you don&#8217;t need to link against OpenSSL
    to use Libevent unless you are <em>actually</em> using encrypted
    connections.
</p>
</dd>
</dl></div>
<h3 id="_the_headers">The Headers</h3><div style="clear:left"></div>
<div class="paragraph"><p>All current public Libevent headers are installed under the <em>event2</em>
directory.  Headers fall into three broad classes:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
API headers
</dt>
<dd>
<p>
    An API header is one that defines current public interfaces to
    Libevent.  These headers have no special suffix.
</p>
</dd>
<dt class="hdlist1">
Compatibility headers
</dt>
<dd>
<p>
    A compatibility header includes definitions for deprecated
    functions.  You shouldn&#8217;t include it unless you&#8217;re porting a
    program from an older version of Libevent.
</p>
</dd>
<dt class="hdlist1">
Structure headers
</dt>
<dd>
<p>
    These headers define structures with relatively volatile layouts.
    Some of these are exposed in case you need fast access to
    structure component; some are exposed for historical reasons.
    Relying on any of the structures in headers directly can break
    your program&#8217;s binary compatibility with other versions of
    Libevent, sometimes in hard-to-debug ways.  These headers have the
    suffix "_struct.h"
</p>
</dd>
</dl></div>
<div class="paragraph"><p>(There are also older versions of the Libevent headers without the
<em>event2</em> directory.  See "If you have to work with an old version of
Libevent" below.)</p></div>
<h3 id="_if_you_have_to_work_with_an_old_version_of_libevent">If you have to work with an old version of Libevent</h3><div style="clear:left"></div>
<div class="paragraph"><p>Libevent 2.0 has revised its APIs to be generally more rational and
less error-prone.  If it&#8217;s possible, you should write new programs to
use the Libevent 2.0 APIs.  But sometimes you might need to work with
the older APIs, either to update an existing application, or to
support an environment where for some reason you can&#8217;t install
Libevent 2.0 or later.</p></div>
<div class="paragraph"><p>Older versions of Libevent had fewer headers, and did not install them
under "event2":</p></div>
<div class="tableblock">
<table rules="all"
width="80%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="30%" />
<col width="70%" />
<thead>
<tr>
<th align="left" valign="top"> OLD HEADER&#8230; </th>
<th align="left" valign="top"> &#8230;REPLACED BY CURRENT HEADERS</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">event.h</p></td>
<td align="left" valign="top"><p class="table">event2/event*.h, event2/buffer*.h event2/bufferevent*.h
event2/tag*.h</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">evdns.h</p></td>
<td align="left" valign="top"><p class="table">event2/dns*.h</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">evhttp.h</p></td>
<td align="left" valign="top"><p class="table">event2/http*.h</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">evrpc.h</p></td>
<td align="left" valign="top"><p class="table">event2/rpc*.h</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">evutil.h</p></td>
<td align="left" valign="top"><p class="table">event2/util*.h</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>In Libevent 2.0 and later, the old headers still exist as wrappers for
the new headers.</p></div>
<div class="paragraph"><p>Some other notes on working with older versions:</p></div>
<div class="ulist"><ul>
<li>
<p>
Before 1.4, there was only one library, "libevent", that contained
  the functionality currently split into libevent_core and
  libevent_extra.
</p>
</li>
<li>
<p>
Before 2.0, there was no support for locking; Libevent could be
  thread-safe, but only if you made sure to never use the same
  structure from two threads at the same time.
</p>
</li>
</ul></div>
<div class="paragraph"><p>Individual sections below will discuss the obsolete APIs that you
might encounter for specific areas of the codebase.</p></div>
<h4 id="_notes_on_version_status">Notes on version status</h4>
<div class="paragraph"><p>Versions of Libevent before 1.4.7 or so should be considered totally
obsolete.  Versions of Libevent before 1.3e or so should be considered
hopelessly bug-ridden.</p></div>
<div class="paragraph"><p>(Also, please don&#8217;t send the Libevent maintainers any new features for
1.4.x or earlier---it&#8217;s supposed to stay as a stable release.  And
if you encounter a bug in 1.3x or earlier, please make sure that it
still exists in the latest stable version before you report it:
subsequent releases have happened for a reason.)</p></div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Last updated 2009-11-20 19:55:41 EDT
</div>
</div>
</body>
</html>
